…patibility
Surface the OpenAPI document's version (APISchemaVersion) at runtime so an
external client can detect the daemon's HTTP API contract without parsing the
committed schema. This closes the two follow-ups left open by kenn-io#99: the API
schema version in health output, and a documented compatibility contract.
- internal/api: add api_schema_version to HealthResponse, distinct from the
existing schema_version (which is the DB/storage schema). The doc comment
spells out the difference so the two version fields aren't conflated.
- internal/daemon: populate it from APISchemaVersion (the same const stamped
into info.version of the OpenAPI doc), so health and schema never disagree.
- docs/reference: new "HTTP API schema" page covering how to obtain the schema
(kata openapi / committed api/openapi.yaml), what the snapshot is and is not,
the three version fields, and the compatibility expectations (additive
changes unsignalled, breaking changes bump api_schema_version).
- api/openapi.yaml: regenerated; the golden test keeps it in lockstep.
Squashed commits:
- fix(api): make api_schema_version schema-optional (additive, no version
bump): mark the field omitempty so its addition is a genuine additive
change and a client treats an absent value as "daemon older than this
field." Current daemons always populate it.
- fix(api): publish response schemas with additionalProperties:true:
OpenAPIDocument relaxes every response-reachable object schema while
request bodies keep their declared strictness, so strict clients don't
break on additive optional response fields.
- docs(api): correct request-body strictness claim in compatibility notes:
describe what the relaxation pass actually guarantees — it never loosens
request schemas, which stay strict unless a type explicitly opts in.
Part of kenn-io#97.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
wesm
force-pushed
the
feat/health-api-schema-version
branch
from
What
Closes the two follow-ups left open by #99: surface the API schema version in
/api/v1/health, and document the compatibility contract for the publishedOpenAPI schema.
api_schema_versionin/api/v1/health— the value stamped into theOpenAPI document's
info.version(daemon.APISchemaVersion), so an externalclient can detect the HTTP API contract at runtime without parsing the
committed schema. It's distinct from the existing
schema_version, which isthe DB/storage schema (
meta.schema_version); the response doc comment spellsout the difference so the two aren't conflated.
docs/reference/http-api.md— a Reference page covering how to obtain theschema (
kata openapi/ committedapi/openapi.yaml), what the per-releasesnapshot is and isn't, the three version fields, and the compatibility
expectations (additive changes unsignalled; breaking changes bump
api_schema_version).A design note worth a look
api_schema_versionis optional in the schema even though current daemonsalways send it. A version-detection field has to survive version skew: a client
generated from a schema that includes the field still needs to parse the
/healthresponse of an older daemon that predates it, so an absent valueshould read as "older than this field," not a parse failure. Making it required
would also have been a contract change that, by this PR's own documented rules,
should bump
api_schema_version— keeping it additive avoids over-signalling.The net schema delta is a single optional property; the
requiredlist isunchanged.
The committed
api/openapi.yamlis regenerated; the existing golden test keepsit in lockstep with the routes.
Part of #97.